<?xml version="1.0" encoding="iso-8859-15"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15" />
    <title>shairport-sync(7)</title>
    <style type="text/css">
        body { color: black; background-color: white; } 
        a:link, a:visited { color: #900000; }       
        h1 { text-transform:uppercase; font-size: 18pt; } 
        p { margin-left:1cm; margin-right:1cm; } 
        .cmd { font-family:monospace; }
        .file { font-family:monospace; }
        .arg { font-family:monospace; font-style: italic; }
        .opt { font-family:monospace; font-weight: bold;  }
        .manref { font-family:monospace; }
        .option .optdesc { margin-left:2cm; }
      </style>
  </head>
  <body><h1>Name</h1><p>shairport-sync - AirPlay and AirPlay 2 Audio Player</p>

	<h1>Synopsis</h1>
	
      <p class="cmd">shairport-sync <span class="opt">[-djvw]</span>
      <span class="opt">[-a </span><span class="arg">service-name</span><span class="opt"> | --name=</span><span class="arg">service-name</span><span class="opt">]</span>
      <span class="opt">[-B </span><span class="arg">command</span><span class="opt"> | --onstart=</span><span class="arg">command</span><span class="opt">]</span>
      <span class="opt">[-c </span><span class="arg">configurationfile</span><span class="opt"> | --configfile=</span><span class="arg">configurationfile</span><span class="opt">]</span>
      <span class="opt">[-d | --daemon]</span>
      <span class="opt">[-E </span><span class="arg">command</span><span class="opt"> | --onstop=</span><span class="arg">command</span><span class="opt">]</span>
      <span class="opt">[-g | --get-cover-art]</span>
      <span class="opt">[-j | --justDaemoniseNoPIDFile]</span>
      <span class="opt">[--logOutputLevel]</span>
      <span class="opt">[--log-to-syslog]</span>
      <span class="opt">[-L </span><span class="arg">latency</span><span class="opt"> | --latency=</span><span class="arg">latency</span><span class="opt">]</span>
      <span class="opt">[-m </span><span class="arg">backend</span><span class="opt"> | --mdns=</span><span class="arg">backend</span><span class="opt">]</span>
      <span class="opt">[-M | --metadata-enable]</span>
      <span class="opt">[-o </span><span class="arg">backend</span><span class="opt"> | --output=</span><span class="arg">backend</span><span class="opt">]</span>
      <span class="opt">[-p </span><span class="arg">port</span><span class="opt"> | --port=</span><span class="arg">port</span><span class="opt">]</span>
      <span class="opt">[--password=</span><span class="arg">secret</span><span class="opt">]</span>
      <span class="opt">[-r </span><span class="arg">threshold</span><span class="opt"> | --resync=</span><span class="arg">threshold</span><span class="opt">]</span>
      <span class="opt">[--statistics]</span>
      <span class="opt">[-S </span><span class="arg">mode</span><span class="opt"> | --stuffing=</span><span class="arg">mode</span><span class="opt">]</span>
      <span class="opt">[-t </span><span class="arg">timeout</span><span class="opt"> | --timeout=</span><span class="arg">timeout</span><span class="opt">]</span>
      <span class="opt">[--tolerance=</span><span class="arg">frames</span><span class="opt">]</span>
      <span class="opt">[-v | --verbose]</span>
      <span class="opt">[-w | --wait-cmd]</span>
      <span class="opt">[-- </span><span class="arg">audio_backend_options</span><span class="opt">]</span>
      </p>
      <p class="cmd">shairport-sync <span class="opt">-X | --displayConfig</span></p>
      <p class="cmd">shairport-sync <span class="opt">-h</span></p>
      <p class="cmd">shairport-sync <span class="opt">-k</span></p>
      <p class="cmd">shairport-sync <span class="opt">-V</span></p>
	

  <h1>Description</h1>
    <p>Shairport Sync plays AirPlay audio.
    It can be built to stream either from "classic" AirPlay (aka "AirPlay 1")
    or from AirPlay 2 devices.</p>
    
    <p>AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported.
    For AirPlay 2 operation, a companion program called <span class="opt">nqptp</span> must be installed.</p>

    <p>Please see <a class="url" href="https://github.com/mikebrady/shairport-sync">https://github.com/mikebrady/shairport-sync</a> for details.</p>

    <p>The name of the Shairport Sync executable is <span class="opt">shairport-sync</span>.</p>
   
	


	<h1>Configuration File Settings</h1>
	  <p>You should use the configuration file for setting up Shairport Sync because --
	  apart from a few special-purpose commands -- it has a much richer set of options
	  than are available on the command line.
	  This file is usually <span class="file">shairport-sync.conf</span> and is generally located in the
	  System Configuration Directory, which is normally the <span class="file">/etc</span> directory in
	  Linux or the <span class="file">/usr/local/etc</span> directory in BSD unixes.
	  You may need to have root privileges to modify it.</p>

	  <p>(Note: Shairport Sync may have been compiled to use a different configuration
	  directory. You can determine which by performing the command <span class="file">$ shairport-sync
	  -V</span>. The last item in the output string is the value of the
	  <span class="opt">sysconfdir</span>, i.e. the System Configuration Directory.)</p>

	  <p>Within the configuration file, settings are organised into groups, for
	  example, there is a <span class="opt">general</span> group of
	  standard settings, and there is an <span class="opt">alsa</span> group with settings
	  that pertain to the <span class="opt">ALSA</span> back end.
	  Here is an example of a typical configuration file:</p>

	  <p><span class="opt">general = {</span></p>
    <p><p><span class="opt">name = "Mike's Boombox";</span></p></p>
    <p><span class="opt">};</span></p>
    <p><span class="opt"></span></p>
    <p><span class="opt">alsa = {</span></p>
    <p><p><span class="opt">output_device = "hw:0";</span></p></p>
    <p><p><span class="opt">mixer_control_name = "PCM";</span></p></p>
    <p><span class="opt">};</span></p>

	  <p>Users generally only need to set (1) the service name and
	  (2) the output device.
	  
	  If the <span class="opt">name</span> setting is omitted, the service name is derived from the system's hostname.
	  
	  By default, the <span class="opt">ALSA</span> backend will be chosen if included in the build.
	  
	  If the (alsa) output device has a mixer that can be used for volume
	  control, then (3) the mixer name should be specified. It is important
	  to do this if the mixer exists. Otherwise, the
	  maximum output from the output device will be whatever setting the mixer happens to
	  have, which will be a matter of chance and which could be very low or even silent.</p>

	  <p>A sample configuration file with all possible settings, but with all of them
	  commented out, is installed at <span class="file">shairport-sync.conf.sample</span>, within the
	  System Configuration Directory -- <span class="file">/etc</span> in Linux,
	  <span class="file">/usr/local/etc</span> in BSD unixes.</p>
	  
	  <p>The sample configuration file includes extensive documentation of the settings.
	  and is also available at
	  <a class="url" href="https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf">https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf</a>.
	  Please refer to it for the most up-to-date information on configuration file settings.</p>

	

	<h1>Options</h1>

    <p>There are two kinds of command-line options for shairport-sync:
    regular <span class="opt">program options</span> and <span class="opt">audio backend options</span>.
    Program options are
    always listed first, followed by any audio backend options, preceded by
    a <span class="opt">--</span> symbol.</p>
    
    <p>See the EXAMPLES section for sample usages.</p>

  <h1>Program Options</h1>
  <p>Program Options are used by shairport-sync itself.</p>
  

	  <div class="option">
		<p><span class="opt">-a </span><span class="arg">service name</span><span class="opt"> | --name=</span><span class="arg">service
		name</span></p>
		<div class="optdesc"><p>
		Use this <span class="arg">service name</span> to identify this player in iTunes, etc.</p>

		<p>The following substitutions are allowed:
		<span class="opt">%h</span> for the computer's hostname,
		<span class="opt">%H</span> for the computer's hostname with the first letter capitalised (ASCII
		only),
		<span class="opt">%v</span> for the shairport-sync version number, e.g. "3.0.1" and
		<span class="opt">%V</span> for the shairport-sync version string, e.g.
		"3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".</p>
    <p>The default is "%H", which is replaced by the hostname with the first letter
    capitalised.</p>
    </div>
	  </div>

	  <div class="option">
		<p><span class="opt">-B </span><span class="arg">program</span><span class="opt"> | --on-start=</span><span class="arg">program</span></p>
		<div class="optdesc"><p>
		Execute <span class="arg">program</span> when playback is about to begin. Specify the
		full path to the program, e.g. <span class="file">/usr/bin/logger</span>.
		Executable scripts can be used, but they must have the appropriate shebang
    (<span class="file">#!/bin/sh</span>) in the headline.</p>

		<p>If you want shairport-sync to wait until the command has
		completed before starting to play, select the <span class="opt">-w</span> option as well.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-c </span><span class="arg">filename</span><span class="opt"> | --configfile=</span><span class="arg">filename</span></p>
		<div class="optdesc"><p>
		Read configuration settings from <span class="arg">filename</span>. The default is to read them from
		the <span class="file">shairport-sync.conf</span> in the System Configuration Directory --
		<span class="file">/etc</span> in Linux, <span class="file">/usr/local/etc</span> in BSD unixes.
		For information about configuration settings, see the "Configuration File Settings"
		section above.
    </p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-d | --daemon</span></p>
		<div class="optdesc"><p>
		Instruct shairport-sync to demonise itself. It will write its
    Process ID (PID) to a file, usually at
    <span class="file">/var/run/shairport-sync/shairport-sync.pid</span>, which is used by the
    <span class="opt">-k</span>, <span class="opt">-D</span> and <span class="opt">-R</span> options to locate
    the daemon at a later time. See also the <span class="opt">-j</span> option. Only available if
		shairport-sync has been compiled with libdaemon support.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-E </span><span class="arg">program</span><span class="opt"> | --on-stop=</span><span class="arg">program</span></p>
		<div class="optdesc"><p>
		Execute <span class="arg">program</span> when playback has ended. Specify the
		full path to the program, e.g. <span class="file">/usr/bin/logger</span>.
		Executable scripts can be used, but they must have the appropriate shebang
    (<span class="file">#!/bin/sh</span>) in the headline.</p>
		<p>If you want shairport-sync to wait until the command has
		completed before continuing, select the <span class="opt">-w</span> option as well.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-g | --get-coverart</span></p>
		<div class="optdesc"><p>
		This option requires the <span class="opt">-M | --metadata-enable</span> option to be set, and enables
		shairport-sync to request cover art from the source and to process it as metadata.</p>
		</div>
	  </div>

	  <div class="option">
		<p><span class="opt">-h | --help</span></p>
		<div class="optdesc"><p>
		Print brief help message and exit.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-j | justDaemoniseNoPIDFile</span></p>
		<div class="optdesc"><p>
		Instruct shairport-sync to demonise itself. Unlike the <span class="opt">-d</span> option, it will
		not write a Process ID (PID) to a file -- it will just (hence the "j") demonise
		itself.  Only available if shairport-sync has been compiled with libdaemon support.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-k | --kill</span></p>
		<div class="optdesc"><p>
		Kill the shairport-sync daemon and exit. (Requires that the daemon has
		written its PID to an agreed file -- see the <span class="opt">-d</span> option. Only available if
		shairport-sync has been compiled with libdaemon support.)
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">--logOutputLevel</span></p>
		<div class="optdesc"><p>
		Use this to log the volume level when the volume is changed. It may be useful if you
		are trying to determine a suitable value for the maximum volume level. Not available
		as a configuration file setting.
    </p>
    </div>
	  </div>

	  <div class="option">
		<p><span class="opt">--log-to-syslog</span></p>
		<div class="optdesc"><p>
		Warnings, error messages and messages are sent, by default, to <span class="file">STDERR</span>.
		Use this option to route these messages to the <span class="opt">syslog</span> instead.
		This is intended for use when Shairport Sync is operating as a daemon.
    </p><p>See also <span class="opt">--displayConfig</span>.</p>
    </div>
	  </div>

	  <div class="option">
		<p><span class="opt">-L | --latency=</span><span class="arg">latency</span></p>
		<div class="optdesc"><p>
		Use this to set the <span class="arg">default latency</span>, in frames, for audio coming from an
		unidentified source or from an iTunes Version 9 or earlier source. The standard value
		for the <span class="arg">default latency</span> is 88,200 frames, where there are 44,100
    frames to the second.
    </p>
    <p>Please note that this feature is deprecated and will be removed in a future version
    of shairport-sync.</p>
    </div>
	  </div>

	  <div class="option">
		<p><span class="opt">-M | --metadata-enable</span></p>
		<div class="optdesc"><p>
		Ask the client to send metadata. It will be sent, along with metadata generated
		by shairport-sync itself, to a pipe and will also be
		sent as UDP packets.
		If you add the <span class="opt">-g | --get-cover-art</span>
		then cover art included, where available. See <a class="url" href="https://github.com/mikebrady/shairport-sync-metadata-reader">https://github.com/mikebrady/shairport-sync-metadata-reader</a>
		for a sample metadata reader.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">--metadata-pipename=</span><span class="arg">pathname</span></p>
		<div class="optdesc"><p>
		Specify the path name for the metadata pipe.
		Note that <span class="opt">shairport-sync</span> will need write permission on that directory and pipe.
		The default is <span class="file">/tmp/shairport-sync-metadata</span>.
		If you rename the <span class="opt">shairport-sync</span> executable, the default pipe name will change accordingly.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-m </span><span class="arg">mdnsbackend</span><span class="opt"> | --mdns=</span><span class="arg">mdnsbackend</span></p>
		<div class="optdesc"><p>
		Force the use of the specified mDNS backend to advertise the
    player on the network. The default is to try all mDNS backends in order until one
    works.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-o </span><span class="arg">outputbackend</span><span class="opt"> |
		--output=</span><span class="arg">outputbackend</span></p>
		<div class="optdesc"><p>
		Force the use of the specified output backend to play the audio.
    The default is to try the first one.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-p </span><span class="arg">port</span><span class="opt"> | --port=</span><span class="arg">port</span></p>
		<div class="optdesc"><p>
		Listen for play requests on <span class="arg">port</span>. The default is to use port
    5000 for AirPlay and 7000 for AirPlay 2.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">--password=</span><span class="arg">secret</span></p>
		<div class="optdesc"><p>
		Require the password <span class="arg">secret</span> to be able to connect and stream to the
		service. (This only works for AirPlay and not for AirPlay 2.)
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-r </span><span class="arg">threshold</span><span class="opt"> | --resync=</span><span class="arg">threshold</span></p>
		<div class="optdesc"><p>
		Resynchronise if timings differ by more than <span class="arg">threshold</span> frames.
    If the output timing differs from the source timing by more than
    the threshold, output will be muted and a full resynchronisation
    will occur. The default threshold is 2,205 frames, i.e. 50
    milliseconds. Specify <span class="opt">0</span> to disable resynchronisation. This setting is
    deprecated and will be removed in a future version of shairport-sync.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">--statistics</span></p>
		<div class="optdesc"><p>
		Print some performance information to <span class="file">STDERR</span>, or to <span class="opt">syslog</span> if the <span class="opt">-log-to-syslog</span> command line option is also chosen.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-S </span><span class="arg">mode</span><span class="opt"> | --stuffing=</span><span class="arg">mode</span></p>
		<div class="optdesc"><p>
		Interpolate ("stuff") the audio stream using the <span class="arg">mode</span>.
		"Stuffing" refers to the
    process of adding or removing frames of audio to or from the
    stream sent to the output device in order to keep it synchronised
    with the player.
    The <span class="opt">basic</span> mode is normally almost completely inaudible.
    The alternative mode, <span class="opt">soxr</span>, is even less obtrusive but
    requires much more processing power. For this mode, support for
    <span class="opt">libsoxr</span>, the SoX Resampler Library, must be selected when
    <span class="opt">shairport-sync</span> is built.
    
    The default setting, <span class="opt">auto</span>, allows Shairport Sync to choose
    <span class="opt">soxr</span> mode if the system is powerful enough.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-t </span><span class="arg">timeout</span><span class="opt"> | --timeout=</span><span class="arg">timeout</span></p>
		<div class="optdesc"><p>
		Exit play mode if the stream disappears for more than <span class="arg">timeout</span>
    seconds.</p>
    <p>When shairport-sync plays an audio stream, it starts a play
    session and will return a busy signal to any other sources that
    attempt to use it. If the audio stream disappears for longer
    than <span class="arg">timeout</span> seconds, the play session will be terminated.
    If you specify a timeout time of <span class="opt">0</span>,
    shairport-sync will never signal that
    it is busy and will not prevent other sources from "barging in"
    on an existing play session. The default value is 120 seconds.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">--tolerance=</span><span class="arg">frames</span></p>
		<div class="optdesc"><p>
		Allow playback to be up to <span class="arg">frames</span> out of exact synchronization before
		attempting to correct it.
		The default is 88 frames, i.e. 2 ms. The smaller the tolerance, the more likely it is
		that overcorrection will occur.
		Overcorrection is when more corrections (insertions and deletions) are made than are
		strictly necessary to keep the stream in sync. Use the <span class="opt">--statistics</span> option
		to monitor correction levels. Corrections should not greatly exceed net corrections.
		This setting is deprecated and will be removed in a future version of shairport-sync.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-V | --version</span></p>
		<div class="optdesc"><p>
		Print version information and exit.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-v | --verbose</span></p>
		<div class="optdesc"><p>
		Print debug information to the <span class="file">STDERR</span>, or to <span class="opt">syslog</span> if the <span class="opt">-log-to-syslog</span> command line option is also chosen.
		Repeat up to three times (i.e. <span class="opt">-vv</span> or <span class="opt">-vvv</span>) for more detail. You should use <span class="opt">-vvv</span> very sparingly -- it is really noisy.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-w | --wait-cmd</span></p>
		<div class="optdesc"><p>
		Wait for commands specified using <span class="opt">-B</span> or <span class="opt">-E</span> to complete before
    continuing execution.
		</p></div>
	  </div>

	  <div class="option">
		<p><span class="opt">-X | --displayConfig</span></p>
		<div class="optdesc"><p>
		This logs information relating to the configuration of Shairport Sync.
		It can be very useful for debugging. The information logged is 
		some host OS information, the Shairport Sync version string
		(which indicates the build options used when <span class="opt">shairport-sync</span> was built),
		the contents of the command line that invoked Shairport Sync,
		the name of the configuration file and the active settings therein.</p>
		<p>If this is the only option on the command line, <span class="opt">shairport-sync</span> will
		terminate after displaying the information.</p>
		</div>
	  </div>

  <h1>Audio Backend Options</h1>
  <p>Audio Backend Options are command-line options that are passed to the chosen audio backend.
  They are always preceded by the <span class="opt">--</span> symbol to introduce them and to separate them from
  any preceding program options. In this way, option letters can be used as program
  options and reused as audio backend options without ambiguity.</p>

  <p>Audio backends are listed with their corresponding Audio Backend Options in the help text provided by the help (<span class="opt">-h</span> or <span class="opt">--help</span>) option.</p>
  
	

  <h1>Examples</h1>
  <p>Here is a slightly contrived example:</p>
      <p class="cmd">shairport-sync
      <span class="opt">-a "Joe's Stereo"</span>
      <span class="opt">-o alsa</span>
       <span class="opt">--</span>
      <span class="opt">-d hw:1,0</span>
      <span class="opt">-m hw:1</span>
      <span class="opt">-c PCM</span>
      </p>
  <p>The program will be visible as
  "Joe's Stereo" ( <span class="opt">-a "Joe's Stereo"</span> ).
  The program option <span class="opt">-o alsa</span> specifies that the <span class="opt">alsa</span> backend be used, thus that audio should be output into the <span class="opt">ALSA</span> audio subsystem.
  The audio backend options following the <span class="opt">--</span> separator are passed to the <span class="opt">alsa</span> backend and specify
  that the audio will be output on subdevice 0 of soundcard 1
  ( <span class="opt">-d hw:1,0</span> ) and will take advantage of the same sound card's mixer
  ( <span class="opt">-m hw:1</span> ) using the level control named "PCM" ( <span class="opt">-c "PCM"</span> ).
  </p>
  <p>The example above is slightly contrived:
  Firstly, if the <span class="opt">alsa</span> backend has been included in the build, it will be the default, so it doesn't need to be specified and the <span class="opt">-o alsa</span> option could be omitted.
  Secondly, subdevice 0 is the default for a soundcard, so the output device could simply be written <span class="opt">-d hw:1</span>.
  Thirdly, when a mixer name is given ( <span class="opt">-c "PCM"</span> ), the default is that the mixer is on the output device, so the <span class="opt">-m hw:1</span> is unnecessary here.
  Using these defaults and simplifications gives the following command:</p>
       <p class="cmd">shairport-sync
      <span class="opt">-a "Joe's Stereo"</span>
       <span class="opt">--</span>
      <span class="opt">-d hw:1</span>
      <span class="opt">-c PCM</span>
      </p>

  

	<h1>Credits</h1>
	<p>Mike Brady (<a class="url" href="https://github.com/mikebrady">https://github.com/mikebrady</a>) developed Shairport Sync from Shairport by James Wah (<a class="url" href="https://github.com/abrasive">https://github.com/abrasive</a>).</p>
	

	<h1>Comments</h1>
	<p>This man page was written using <a class="manref" href="http://masqmail.cx/xml2man/">xml2man(1)</a> by Oliver Kurth.</p>
	

  </body>
</html>
